<!DOCTYPE doctype PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN">

<HTML>
  <HEAD>
    <META name="generator" content=
    "HTML Tidy for Java (vers. 2009-12-01), see jtidy.sourceforge.net">

    <TITLE>Debugger: Stack</TITLE>
    <META http-equiv="Content-Type" content="text/html; charset=windows-1252">
    <LINK rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
  </HEAD>

  <BODY lang="EN-US">
    <H1><A name="plugin"></A>Debugger: Stack</H1>

    <DIV class="image">
      <IMG alt="" src="images/DebuggerStackPlugin.png">
    </DIV>

    <P>The stack window displays the current trace's execution stack, as unwound and reported by
    the target. Not all debuggers will unwind the stack, in which case, this window displays only
    the innermost frame. When emulation is used to generate the current machine state, only a
    single synthetic frame is shown. See the <A href="#unwind_stack">Unwind Stack</A> action for an
    alternative mechanism that unwinds using Ghidra's program databases and works during emulation.
    Level 0 always refers to the innermost frame, and each incremental level refers to the next
    caller in the chain &mdash; most of the time. The current frame comprises one element of the
    tool's current <EM>coordinates</EM>. Double-clicking a frame <EM>activates</EM> new
    coordinates, potentially causing other windows to display different information. Namely, the <A
    href="help/topics/DebuggerRegistersPlugin/DebuggerRegistersPlugin.html">Registers</A> window
    will show registers for the current frame, assuming they can be retrieved. The Listings may
    also navigate to the current frame's program counter.</P>

    <H2>Table Columns</H2>

    <P>The stack table has the following columns:</P>

    <UL>
      <LI>Level - the level of the frame, counting 0-up starting at the innermost frame.</LI>

      <LI>PC - the address of the instruction to execute next, or upon return of the callee for
      non-0 frames. Different debuggers may have different subtleties in how they report PC.</LI>

      <LI>Function - the name of the function containing the PC, if Ghidra has the corresponding
      module image imported, analyzed, and mapped.</LI>

      <LI>Module - the name of the module containing the PC.</LI>
    </UL>

    <H2>Action</H2>

    <P>The stack plugin provides a single action:</P>

    <H3><A name="unwind_stack">Unwind Stack (U)</A></H3>

    <P>This action is in the main menu: <B>Debugger &rarr; Analysis &rarr; Unwind from frame 0</B>.
    It attempts to unwind the current thread's stack segment, creating frame data units in the
    listing. It starts by reading the program counter and stack pointer from the innermost frame of
    the current thread. It then maps the program counter to the program database and analyzes the
    function containing it. If successful, it can determine the frame's base address then locate
    variables, saved registers, and the return address. Knowing the return address and frame depth,
    it can derive the program counter and stack pointer of the next frame and unwind it in the same
    manner. This proceeds until analysis fails or the stack segment is exhausted. For best results,
    ensure you have imported and opened the Ghidra program database for every module, or at least
    the subset you expect to see in your stack. To view the results, navigate to or follow the
    stack pointer in a Dynamic Listing. The Stack window <EM>does not</EM> display Ghidra's
    unwinding results.</P>

    <DIV class="image">
      <IMG alt="" src="images/DebuggerStackUnwindInListing.png">
    </DIV>

    <P>Each call record generates a structure data unit derived from the function's frame. The
    exact contents of the structure depend on the current program counter within that function.
    Only those entries actually allocated at the program counter are included. Each field in that
    structure can be one of five kinds:</P>

    <UL>
      <LI><B>Local stack variable:</B> These are named with the <CODE>local_</CODE> prefix. They
      correspond exactly to those entries found in the function's stack frame in the program
      database.</LI>

      <LI><B>Stack parameter:</B> These are named with the <CODE>param_</CODE> prefix. They
      correspond exactly to those entries found in the function's stack frame in the program
      database.</LI>

      <LI><B>Return address:</B> This is named <CODE>return_address</CODE>. It is determined by
      interpreting the function's machine code.</LI>

      <LI><B>Saved register:</B> These are named with the <CODE>saved_</CODE> prefix. They are
      determined by interpreting the function's machine code.</LI>

      <LI><B>Slack space:</B> These are named with the <CODE>offset_</CODE> prefix (or
      <CODE>posOff_</CODE> for positive offsets). They represent unused or unknown entries.</LI>
    </UL>

    <P>The frame entries are <EM>not</EM> automatically updated when a function's frame changes in
    a program database. To update the unwind after changing a function's stack frame, you must
    unwind again.</P>
  </BODY>
</HTML>
